docs: improve documentation content structure#292
Open
GaneshPatil7517 wants to merge 10 commits intoapache:mainfrom
Open
docs: improve documentation content structure#292GaneshPatil7517 wants to merge 10 commits intoapache:mainfrom
GaneshPatil7517 wants to merge 10 commits intoapache:mainfrom
Conversation
- community.adoc: Update to use GitHub Discussions instead of Nabble - forums.adoc: Restructure and add GitHub Discussions section - issues.adoc: Update from Jira to GitHub Issues for issue tracking
Optimize the Validator to use buffered file reading with early exit instead of reading entire files into memory. JBake metadata headers are always at the top of .adoc files, so we only need to read the first few lines to validate them. Changes: - Use BufferedReader instead of Files.readAllLines() - Exit early when validation passes (date found or redirect page) - Limit reading to first 50 lines (headers are typically in first 10) This reduces memory usage and improves validation speed for large files.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the structure and completeness of the Apache Shiro documentation by replacing stub content with comprehensive documentation, enhancing navigation through cross-references, and clarifying how different documentation resources fit together.
Changes:
- Replaced TODO/TBD stub content with comprehensive documentation for Authenticator and Authorizer components
- Added "See Also" sections throughout documentation pages to improve navigation and discoverability
- Enhanced documentation hub pages (guides.adoc, documentation.adoc, get-started.adoc) with better organization and structure
- Added Migration Notes sections to release blog posts to help users understand upgrade paths
- Optimized Java validator for better performance when parsing documentation headers
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/site/content/authenticator.adoc | Complete rewrite from TODO stub to comprehensive documentation about the Authenticator component |
| src/site/content/authorizer.adoc | Complete rewrite from TODO stub to comprehensive documentation about the Authorizer component |
| src/site/content/java-authorization-guide.adoc | Replaced "TBD" stub with caching content and added "See Also" navigation section |
| src/site/content/java-authentication-guide.adoc | Added "See Also" navigation section for cross-referencing related topics |
| src/site/content/reference.adoc | Added introductory text, helpful tip for newcomers, and "See Also" section |
| src/site/content/guides.adoc | Restructured with logical sections (Getting Started, Core Concepts, Advanced Topics) and improved descriptions |
| src/site/content/get-started.adoc | Added "Next Steps" and "Need Help?" sections to guide users after completing tutorials |
| src/site/content/documentation.adoc | Enhanced hub structure with better organization and clearer navigation paths |
| src/site/content/forums.adoc | Simplified structure and removed deprecated GitHub Discussions reference |
| src/site/content/community.adoc | Removed GitHub Discussions reference and simplified community resources |
| src/site/content/issues.adoc | Cleaned up jbake-tags metadata by removing deprecated "jira" tag |
| src/site/content/blog/2024/11/apache-shiro-202-released.adoc | Added Migration Notes section to help users upgrading from Shiro 1.x |
| src/site/content/blog/2025/07/apache-shiro-205-released.adoc | Added Migration Notes section to help users upgrading from Shiro 1.x |
| src/site/content/blog/2025/11/apache-shiro-206-released.adoc | Added Migration Notes section to help users upgrading from Shiro 1.x |
| src/main/java/org/apache/shiro/site/Validator.java | Optimized header parsing to read only first 50 lines instead of entire files, with early returns for valid cases |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
lprimak
requested changes
Feb 9, 2026
Contributor
lprimak
left a comment
lprimak
left a comment
There was a problem hiding this comment.
This PR is entangled with other PRs... can't review
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR improves the overall structure and completeness of the Shiro site
documentation by addressing stub content, improving navigation, and clarifying
how tutorials, guides, and release notes fit together.
Resolves #287.